Broadband - Trouble Ticket API - TMF621

This section defines the key fields used in the TMF621 Trouble Ticket API. Attributes listed here may appear in request or response payloads depending on the operation. Fields are derived from TMF621 v5.0.0 and follow TMF630 REST design principles.

API request payload

POST /troubleTicket

Section	Field Name	Example Field Value	Description
HTTP Header Name	Correlation-ID	c97ded75-44fa-4b69-9f3b-01d513a41efe	A GUID to relate requests belonging to the same transaction
Payload First Class Attribute	description	No dial tone on customer line	A String. Description of the trouble or issue. Mandatory.
Payload First Class Attribute	name	Voice QOS, faint calls	A short description provided by the user that create the ticket
Payload First Class Attribute	ticketType	fault	Indicates category of issue. To be set to fault. Mandatory.
Payload First Class Attribute	severity	High	The severity of the issue, as per partners' definition. Mandatory.
Payload First Class Attribute	dateFirstFound	2025-01-02T09:00:00Z	Mandatory. Represents when the fault occurred for the first time.
Payload First Class Attribute	twentyFourHourAccess	true	Mandatory. Defines whether the EU will be available 24 hour in the event an appointment is required.
Payload First Class Attribute	earliestNextAccessDateTime	2025-01-02T09:00:00Z	Conditional, mandatory if twentyFourHourAccess is false.
Payload First Class Attribute	latestAccessDateTime	2025-01-01T17:00:00Z	Conditional, mandatory if twentyFourHourAccess is false.
Payload First Class Attribute	troubleTicketCharacteristic	See troubleTicketCharacteristic table	An array of Characteristic objects, defined by TMF pattern.
Payload First Class Attribute	attachment	See attachment table	An array of AttachmentRefOrValue. Optional file evidence; 1 allowed per submission.
Payload First Class Attribute	note	See note table	Array of Note objects (inline). Free-text notes from partners, suppliers, end users and PXC agents.
Payload First Class Attribute	relatedEntity	See relatedEntity table	References the product, service, or billing account affected by the fault.
Payload First Class Object	troubleTicketSpecification	See troubleTicketSpecification table	A reference to a predefined classification of the trouble ticket.
Payload First Class Attribute	relatedParty	See relatedParty table	Identifies the people or organizations involved with the ticket.
Payload First Class Attribute	troubleTicketRelationship	See troubleTicketRelationship table	Relates the current trouble ticket to other tickets (e.g., parent, duplicateOf).
Payload First Class Attribute	externalIdentifier	See externalIdentifier table	Partner reference ID, mapped to TMF621 externalIdentifier array.
Payload First Class Object	appointment	See appointment table	Reference to TMF646 appointment (id, href, description).
TMF metadata	@type	PartnerTroubleTicket	Subclass indicator for TroubleTicket extension. Mandatory.
TMF metadata	@baseType	TroubleTicket	Core resource type. Mandatory.
TMF metadata	@schemaLocation	https://.../schema/PartnerTroubleTicket.json	Defines schema for extended attributes.

troubleTicketCharacteristic Values Table

TroubleTicketCharacteristics must be filled in consistently with the specification selected. troubleTicketCharacteristic objects must align with the structure and constraints defined by the associated troubleTicketSpecification. Required fields, cardinality, and data types are all governed by that definition. Values must adhere to any regex, allowedValues, or min/max cardinality constraints defined at the specification level.

troubleTicketCharacteristic

Attachment Table

Note Table

"note" is an array that captures interactions between actors such as the Partner, End User, PXC Agent and Supplier. Each new note is appended to the existing array of notes. Only one note may be included per operation (e.g., POST or PATCH).

relatedEntity Table

The relatedEntity array identifies the product, service, or billing account affected by the fault, using role-based references. Note: Each ticket must include one affectedEntity (product or service) and one relatedAccount (billing account), allowing the backend to validate ownership and link the ticket to the correct asset.

troubleTicketSpecification Table

relatedParty Table

troubleTicketRelationship Table

The troubleTicketRelationship attribute allows linking a ticket to other related tickets (e.g., parent, child, duplicateOf) to support lifecycle tracking and dependency management. The relationshipType field defines the direction and nature of the relationship between the current trouble ticket and another one.

For example, if relationshipType is set to "parent", then the referenced ticket ID in troubleTicketRelationship.id is the parent of the ticket being retrieved via GET /troubleTicket/{id}. This applies consistently to all relationship types . The value of relationshipType always describes the role of the related ticket from the perspective of the ticket being returned.

Note: Partners will not be permitted to POST this field for now; relationships will be calculated by the backend and returned in responses when relevant.

externalIdentifier Table

The externalIdentifier array allows tracking references associated with the ticket, such as those used by partners and suppliers.

Note: Partners are encouraged to provide a partnerRef on ticket creation; a supplierRef will be assigned by the backend and shared in responses where applicable.

Appointment Table

The appointment.id value used in the appointment object (e.g., in POST /troubleTicket or PATCH /troubleTicket/{id}) must be a valid appointment reference issued by PXC via the /appointment API. Partners must ensure they only reference appointments previously retrieved or booked through the appointing interface.

Example POST createTroubleTicket payload:

{
   "description":"Voice QOS, unable to authenticate issue reported by customer. Customer reports bad service when calling.",
   "name":"Voice QOS, faint calls",
   "ticketType":"Fault",
   "severity":"High",
   "dateFirstFound":"2025-02-25T00:00:00Z",
   "twentyFourHourAccess":true,
   "troubleTicketCharacteristic":[
      {
         "name":"faultType",
         "value":"Faint calls",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"frequency",
         "value":"Intermittent",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"examplesWhenFaultOccurs",
         "value":"Every Tuesday evening at 9 PM",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"allCPEChecksComplete",
         "value":true,
         "valueType":"boolean",
         "@type":"BooleanCharacteristic"
      },
      {
         "name":"numberDialled",
         "value":"016-1234-567-89",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"authorizeEngineerEffort",
         "value":false,
         "valueType":"boolean",
         "@type":"BooleanCharacteristic"
      },
      {
         "name":"safetyNote",
         "text":"Beware the dog in the front garden",
         "valueType":"string",
         "@type":"StringCharacteristic"
      }
   ],
   "attachment":[
      {
         "description":"Speed test screenshot attached for more information.",
         "attachmentType":"screenshot",
         "mimeType":"image/png",
         "name":"Speed_test_image",
         "content":"iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAIAAAD7GkWBAA",
         "@type":"Attachment"
      }
   ],
   "note":[
      {
         "text":"This is very urgent, please sort this out as soon as possible",
         "author":"Jane Smith",
         "source":"endUser",
         "@type":"PartnerNote",
         "@baseType":"Note"
      }
   ],
   "relatedEntity":[
      {
         "role":"affectedEntity",
         "@type":"RelatedEntity",
         "entity":{
            "id":"SOGEA777",
            "@type":"EntityRef",
            "@referredType":"Service"
         }
      },
      {
         "role":"relatedAccount",
         "@type":"RelatedEntity",
         "entity":{
            "id":"XX788956566",
            "@type":"EntityRef",
            "@referredType":"BillingAccount"
         }
      }
   ],
   "troubleTicketSpecification":{
      "id":"Voice-QOS",
      "@type":"TroubleTicketSpecificationRef"
   },
   "relatedParty":[
      {
         "role":"reportingParty",
         "partyOrPartyRole":{
            "@type":"Organization",
            "@baseType":"Party",
            "tradingName":"<CompanyName>",
            "contactMedium":[
               {
                  "contactType":"primary",
                  "phoneNumber":"+4412345",
                  "@type":"PhoneContactMedium",
                  "@baseType":"ContactMedium"
               },
               {
                  "contactType":"primary",
                  "emailAddress":"john.doe@<example>.com",
                  "@type":"EmailContactMedium",
                  "@baseType":"ContactMedium"
               },
               {
                  "contactType":"secondary",
                  "emailAddress":"support@<example>.co.uk",
                  "@type":"EmailContactMedium",
                  "@baseType":"ContactMedium"
               }
            ]
         },
         "@type":"RelatedPartyOrPartyRole"
      },
      {
         "role":"endUser",
         "partyOrPartyRole":{
            "@type":"Individual",
            "@baseType":"Party",
            "givenName":"Jane",
            "familyName":"Smith",
            "contactMedium":[
               {
                  "contactType":"primary",
                  "phoneNumber":"+449876543210",
                  "@type":"PhoneContactMedium",
                  "@baseType":"ContactMedium"
               },
               {
                  "contactType":"primary",
                  "emailAddress":"Jane.smith@<example>.com",
                  "@type":"EmailContactMedium",
                  "@baseType":"ContactMedium"
               }
            ]
         },
         "@type":"RelatedPartyOrPartyRole"
      }
   ],
   "externalIdentifier":[
      {
         "id":"PART123456",
         "owner":"<PartnerOwnerName>",
         "externalIdentifierType":"partnerRef",
         "@type":"ExternalIdentifier"
      }
   ],
   "appointment":{
      "id":"APP67789",
      "@type":"AppointmentRef"
   },
   "@type":"PartnerTroubleTicket",
   "@baseType":"TroubleTicket"
}

Response Shaping (fields parameter)

The TMF standard defines a fields query parameter to allow clients to limit which fields are included in API responses. However, this parameter is currently not fully supported in the implementation of the Trouble Ticket API.

• Any use of fields in the request of POST /troubleTicket will be ignored.
• A default list of attributes will be returned in the response, with href to get the full ticket, if required.